Insights API

Overview

Insights reports are one of IQM's analytics tools that help Advertisers quickly identify trends and apply precise adjustments to deliver better results for Campaigns. With pre-defined metrics and dimensions, Insights reports can be generated for Voter Level Data Reports.

Voter Level Data (VLD) Reports offer Insights about targeting in current or prior political Campaigns. These Reports include ad exposure, engagement data, demographic data, and voting-history details by voter.

More resources:

• Reporting and Analytics Help Center Article
• Insights API Guidelines

Authentication

Use the following header parameters for all requests:

Headers
Authentication string required	Authentication bearer token See Authentication Guide
X-IAA-OW-ID integer required	Organization Workspace ID Header

Voter Level Data Reports

VLD Resource Properties

Resource Properties

vldId integer	VLD ID
vldName string	VLD name
vldStatus integer	VLD Status Type ID
ioId integer	Insertion Order ID
ioName string	Insertion Order name
ioTypeId integer	Insertion Order Budget Type ID
isCampaignEligible boolean	Indicates that Campaign is eligible for VLD Report: true
vldCreatedOn integer	Unix epoch timestamp of creation date, in milliseconds
vldStartDate / startDate integer	Unix epoch timestamp of start date, in milliseconds
vldEndDate / endDate integer	Unix epoch timestamp of end date, in milliseconds
campaignId integer	Campaign ID
campaignName string	Campaign name
campaignStatus string	Campaign Status Type
creativeTypeId integer	Creative Type ID
campaignVldTimezoneId integer	Timezone ID
vldReportCreatable boolean	Indicates if VLD Report can be generated for the given Campaign and date range (true)
vldChargeableImps integer	The number of chargeable impressions for the requested VLD Report
vldChargedImps integer	The number of impressions for which the VLD Report is already generated
vldChargeableCost integer	Cost to generate the VLD Report
vldChargedCost integer	Cost of VLD Report that is already generated
fundsAvailable boolean	Indicates if sufficient funds are available in the Advertiser's account to generate the VLD Report (true)
effectiveVldRate integer	Margin rate set by the admin and workspace for generating VLD Report

---

Get List of VLD Reports

GET /api/v3/ins/vld-reports

Get a list of VLD Reports based on search filters.

Query Parameters
searchField string	Search results by keyword
noOfEntries integer	Maximum number of entries per page, default: 200
pageNo integer	Number of pages for retrieved data
sortBy string	Sorts by ascending (+) or descending (-), default: -vldId

JSON

Response 200

{
  "success": true,
  "data": {
    "totalRecords": 10,
    "vldReportDataList": [
      {
        "vldId": 10,
        "vldName": "530667_VLD_Insights_7",
        "campaignName": "prod-campaign-21145",
        "campaignId": 21145,
        "vldStatusId": 3,
        "startDate": 1603152000,
        "endDate": 1603411200,
        "ioId": 5,
        "ioName": "Corporate, Inc.",
        "isCampaignEligible": false,
        "vldCreatedOn": 1721253632,
        "creativeTypeId": 11,
        "campaignVldTimezoneId": 29,
        "ioTypeId": 1
      },
      {
        "vldId": 9,
        "vldName": "530667_VLD_Insights_6",
        "campaignName": "Campaign-4949",
        "campaignId": 4949,
        "vldStatusId": 3,
        "startDate": 1603152000,
        "endDate": 1603411200,
        "ioId": 15,
        "ioName": "Quinton for Mayor",
        "isCampaignEligible": false,
        "vldCreatedOn": 1720325578,
        "creativeTypeId": 14,
        "campaignVldTimezoneId": 29,
        "ioTypeId": 1
      }
    ],
    "filteredRecords": 10
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          totalRecords: number;
          vldReportDataList: {
            vldId: number;
            vldName: string;
            campaignName: string;
            campaignId: number;
            vldStatusId: number;
            startDate: number;
            endDate: number;
            ioId: number;
            ioName: string;
            isCampaignEligible: boolean;
            vldCreatedOn: number;
            creativeTypeId: number;
            campaignVldTimezoneId: number;
            ioTypeId: number;
          }[];
          filteredRecords: number;
        }
      }
    };
  };
};

function getVLDReportList(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://app.iqm.com/api/v3/ins/vld-reports',
    params: {
      query?: {
        searchField?: `string`,
        pageNo?: `number`,
        noOfEntries?: `number`,
        sortBy?: `string`,
      },
    },
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Get List of Campaigns Eligible for VLD Reports

GET /api/v3/ins/vld/campaigns

Get a list of Campaign IDs by status eligible for VLD Report generation.

Response Properties

running array of integers	Campaign IDs with "running" status
paused array of integers	Campaign IDs with "paused" status
expired array of integers	Campaign IDs with "expired" status

JSON

Response 200

{
  "success": true,
  "data": {
    "running": [
      12345,
      12543
    ],
    "paused": [
      54321,
      34521
    ],
    "expired": [
      33452,
      22453
    ]
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          running: number[];
          paused: number[];
          expired: number[];
        }
      }
    };
  };
};

function getStatusWiseCampaignsForVLDReports(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://app.iqm.com/api/v3/ins/vld/campaigns',
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Generate VLD Report

POST /api/v3/ins/vld-report

This API calculates the cost for the impressions for the Voter Level Data Reports based on the impressions and mark up charged on the Organization and then creates the VLD Reports.

info

A Campaign must meet the following eligibility criteria to generate VLD Report:

• Must be political Campaign
• "running", "expired" (within last two years), "paused" status
• Must have duration of 3 or more days
• Creation date: Sept. 16, 2024 or later
• Voter location: all US states (except Oregon)
• Audience type: Matched Audience

Request Schema
vldStartDate integer	Unix epoch timestamp of start date, in milliseconds
vldEndDate integer	Unix epoch timestamp of end date, in milliseconds
campaignId integer	Campaign ID
vldId integer	Generate Insights Report again for VLD ID

JSON

Request Sample

{
  "campaignId": 12345,
  "vldStartDate": 1722311000,
  "vldEndDate": 1722315000
}

Response 200

{
  "success": true,
  "data": {
    "vldReportCreated": true,
    "campaignId": 1,
    "campaignName": "Campaign Name",
    "campaignStatus": "running",
    "vldStartDate": 1722311000,
    "vldEndDate": 1722315000,
    "vldChargeableImps": 1000,
    "vldChargedImps": 100,
    "vldChargeableCost": 1000,
    "vldChargedCost": 100,
    "fundsAvailable": true
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          vldReportCreated: boolean;
          campaignId: number;
          campaignName: string;
          campaignStatus: string;
          vldStartDate: number;
          vldEndDate: number;
          vldChargeableImps: number;
          vldChargedImps: number;
          vldChargeableCost: number;
          vldChargedCost: number;
          fundsAvailable: boolean
        }
      }
    };
  };
};

function generateVLDReports(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/ins/vld-report',
    requestBody: {
      content: {
        "application/json": {
          campaignId?: `number`,
          vldId?: `number`,
          vldStartDate?: `number`,
          vldEndDate?: `number`,
        }
      }
    }
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Get Cost Assessment for VLD Report

POST /api/v3/ins/vld-reports/computation

Calculates the cost for the impressions for the VLD Report based on impressions and the mark up charged on the Organization.

Request Schema
campaignId integer	Campaign ID
vldStartDate integer	Unix epoch timestamp of start date, in milliseconds
vldEndDate integer	Unix epoch timestamp of end date, in milliseconds

JSON

Request Sample

{
  "campaignId": 1,
  "vldStartDate": 1722311000,
  "vldEndDate": 1722315000
}

Response 200

{
  "success": true,
  "data": {
    "vldReportCreated": true,
    "campaignId": 1,
    "campaignName": "Campaign Name",
    "campaignStatus": "running",
    "vldStartDate": 1722311000,
    "vldEndDate": 1722315000,
    "vldChargeableImps": 1000,
    "vldChargedImps": 100,
    "vldChargeableCost": 1000,
    "vldChargedCost": 100,
    "fundsAvailable": true
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          vldReportCreated: boolean;
          campaignId: number;
          campaignName: string;
          campaignStatus: string;
          vldStartDate: number;
          vldEndDate: number;
          vldChargeableImps: number;
          vldChargedImps: number;
          vldChargeableCost: number;
          vldChargedCost: number;
          fundsAvailable: boolean
        }
      }
    };
  };
};

function getChargeableImpressionsDataForVLDReports(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/ins/vld-reports/computation',
    requestBody: {
      content: {
        "application/json": {
          campaignId?: `number`,
          vldId?: `number`,
          vldStartDate?: `number`,
          vldEndDate?: `number`,
        }
      }
    }
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Download VLD Insight Report

POST /api/v3/ins/vld-report/download

Get a download link for a VLD insight Report in CSV or XLSX format.

Request Schema
fileTypeId integer	File type ID XLSX: 1 CSV: 2
vldId integer	VLD ID

Response Properties

vldReportUrl string

VLD Report File URL

JSON

Response 200

{
  "success": true,
  "data": {
    "vldReportUrl": "https://tem.domain.s3.amazonaws.com/vld-campaigns/ds/2024-08-20/503481_Insights_1.xlsx?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20240820T112818Z&X-Amz-"
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          vldReportUrl: string;
        }
      }
    };
  };
};

function getVLDReportDownloadUrl(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/ins/vld-reports/download',
    requestBody: {
      content: {
        "application/json": {
          fileTypeId?: `number`,
          vldId?: `number`,
        }
      }
    }
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Delete VLD Report

DELETE /api/v3/ins/vld-report

Deletes VLD Reports that are not marked as deleted and have a 'failed' status, requires user authorization and checks if the provided VLD IDs are valid.

Query Parameters
vldId integer	VLD ID

Response Properties

success boolean	Indicates Report was succesfully deleted: true
message string	Success message

JSON

Response 200

{
  "success": true,
  "data": {
    "message": "255944_VLD_Insights_2 deleted successfully"
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          vldReportUrl: string;
        }
      }
    };
  };
};

function deleteFailedVLDReport(): Promise<Responses> {
  const options = {
    method: 'DELETE',
    url: 'https://app.iqm.com/api/v3/ins/vld-report',
    params: {
      query: {
        vldIds: `string`
      }
    }
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}